home *** CD-ROM | disk | FTP | other *** search
/ Mac Expert 1995 Winter / Mac Expert - Winter 95.iso / Les fichiers / Utilitaires divers / Images / RTrace 1.0 ƒ / RTrace-docs / rtrace.man < prev    next >
Encoding:
Text File  |  1992-10-08  |  16.8 KB  |  493 lines  |  [TEXT/ttxt]
  1. (original Unix man page, See the RTrace-Manual for Mac specific documentation)
  2. - - - - - - - - - - - - - - - - - - -
  3. RTRACE(1G)                USER COMMANDS                RTRACE(1G)
  4.  
  5. NAME
  6.      rtrace - ray tracing program
  7.  
  8. SYNOPSIS
  9.      rtrace [options] scene image [>log]
  10.  
  11. AUTHOR
  12.      Antonio Costa, INESC-Norte, 1989 1992
  13.  
  14. DESCRIPTION
  15.      rtrace command performs ray tracing from  a  SFF  text  file
  16.      which  must  describe  a scene with objects, lights, surface
  17.      definitions, textures, etc.  This scene file must be in  the
  18.      appropriate format, as described bellow.
  19.      Basically, ray tracing is an algorithm for the  creation  of
  20.      realistic   images  from  the  geometry  and  attributes  of
  21.      objects, lights, etc.   This  ray  tracer  supports  several
  22.      types   of   objects  (sphere,  box,  bicubic  patch,  cone,
  23.      cylinder, polygon, triangle and text), CSG and  list  opera-
  24.      tions,  different  light  types,  reasonable surface defini-
  25.      tions, lots  of  textures,  several  anti-aliasing  schemes,
  26.      depth of field, stereoscopic image creation and so on...
  27.  
  28. OPTIONS
  29.      [wimage-width] [himage-height]
  30.      The parameters image-width and image-height define the image
  31.      size. Defaults are 256x256.
  32.  
  33.      [Aaliasing-threshold]
  34.      [Sshading-threshold]
  35.      [Tambient-threshold]
  36.      The  parameters  aliasing-threshold  (pixel  supersampling),
  37.      shading-threshold  (shading  rays  propagation) and ambient-
  38.      threshold (ambient rays distribution  caching)  control  the
  39.      image  quality (0-best, 1-poor). Defaults are 0.05, 0.01 and
  40.      0 (no ambient threshold). Good ranges  are  0.1-0.03,  0.01-
  41.      0.001 and 0.01-0.00001, respectively.
  42.  
  43.      [aantialiasing-mode]
  44.      The parameter antialiasing-mode chooses  adaptive  supersam-
  45.      pling  antialiasing (0-default), semi-adaptive supersampling
  46.      antialiasing (1) or normal  supersampling  antialiasing  (2-
  47.      should be used with nonzero focal apertures).
  48.  
  49.      [Bmaskfile]
  50.      The parameter maskfile creates  a  file  with  a  background
  51.      mask,  suitable for mixing images (it is like an alpha chan-
  52.      nel).
  53.  
  54.      [ccluster-size]
  55.      The parameter cluster-size controls the enclosing of objects
  56.      (number  of  grouped  objects  per  cluster)  in  the object
  57.  
  58.      hierarchy. Use a low value for sparse scenes, a  high  value
  59.      for dense scenes (4-default).
  60.  
  61.      [dambient-levels]
  62.      The parameter ambient-levels defines the number  of  shading
  63.      levels (shading tree depth) in which ambient lighting calcu-
  64.      lations will be done through  ray  distribution  (0-default,
  65.      ie, no ray distribution). Use low values!
  66.  
  67.      [Dambient-samples]
  68.      The parameter ambient-samples defines the maximum number  of
  69.      distributed rays to be used in ambient lighting calculations
  70.      (16-default). Again, use with care.
  71.  
  72.      [iintersect-mode]
  73.      The parameter intersect-mode chooses, in adaptive  supersam-
  74.      pling antialiasing, between testing all scene objects (1) or
  75.      only the objects found at the pixel corners and  inside  (0-
  76.      default;  this greatly reduces CPU time, but with very small
  77.      objects, it sometimes fails).
  78.  
  79.      [Iintersect-adjust-mode]
  80.      The parameter  intersect-adjust-mode  avoids  some  problems
  81.      with  invalid  self-intersections  (1)  (0-default).  Scenes
  82.      with text objects should be traced with this parameter equal
  83.      to 1.
  84.  
  85.      [jjittering-mode]
  86.      The parameter jittering-mode chooses jittered  sampling  (1)
  87.      or not (0-default). Sometimes, activating it produces better
  88.      images from scenes with small tricky details.
  89.  
  90.      [llighting-mode]
  91.      The parameter light-mode controls the generation  of  shadow
  92.      rays   through  non-opaque  objects:  0-none  (default),  1-
  93.      partial, 2-full. If a  scene  has  translucent  objects,  to
  94.      obtain realism one should use 1 or 2 (better).
  95.  
  96.      [mshading-mode]
  97.      The parameter shading-mode chooses between  shading  models:
  98.      0-normal  phong,  1-strauss (default but slower) (note: this
  99.      model was developed by Paul Strauss of SGI).
  100.  
  101.      [nnormal-mode]
  102.      The parameter normal-mode controls the correction of surface
  103.      normals,  so  that  it  points  against the incident ray: 0-
  104.      always (default),  1-only  inside  objects.  With  "correct"
  105.      objects, it is good to use 1.
  106.  
  107.      [znormal-check-mode]
  108.      The parameter normal-check-mode controls the  correction  of
  109.      surface  normals  when  textures  that modify the normal are
  110.      used, as they may sometimes create strange surface  effects.
  111.      This tends to happen if the scale of the normal perturbation
  112.      is big.  0-no correction (default), 1-correction.
  113.  
  114.      [Rrawfile]
  115.      The parameter rawfile creates a raw image file, without  any
  116.      antialiasing (all defects show up!).
  117.  
  118.      [psampling-levels]
  119.      The parameter sampling-levels controls the  amount  of  sam-
  120.      pling  levels inside pixels: 0-none ... 3-maximum (default).
  121.      A reasonable value is 2 for high resolutions, but for  small
  122.      ones 3 gives better (and slower) results.
  123.  
  124.      [sshading-levels]
  125.      The parameter shading-levels establishes a  maximum  shading
  126.      tree    depth   (default   is   8).   When   a   scene   has
  127.      transparent/reflective objects, it may be important to lower
  128.      this  parameter,  or  else  the  tracing never stops. In the
  129.      other cases, there should be no problem allowing  it  to  be
  130.      big.
  131.  
  132.      [ttexture-mode]
  133.      The  parameter  texture-mode  allows   the   definition   of
  134.      texture(s)  for the objects: 0-no textures (default), 1-with
  135.      textures  defined  inside  objects  field,  2-with  textures
  136.      defined  after  objects  field. As textures may consume much
  137.      CPU time, they should be activated only for final images.
  138.  
  139.      [vview-mode]
  140.      The parameter view-mode  chooses  the  view  mode:  0-normal
  141.      (default), 1-left eye, 2-right eye.
  142.  
  143.      [Pfocal-aperture]
  144.      The parameter focal-aperture defines the focal  aperture  of
  145.      the  camera  (default 0.0, ie, pinhole camera). If different
  146.      than zero, there is depth of field, and so  adaptive  super-
  147.      sampling antialiasing will not work well.
  148.  
  149.      [Ffocal-distance]
  150.      The parameter focal-distance defines the focal  distance  of
  151.      the  camera  (default  is the distance from the eye point to
  152.      the look point).
  153.  
  154.      [Estereo-separation]
  155.      The  parameter  stereo-separation  controls  the  separation
  156.      between  the  left  and  the  right  eye.   If  negative, it
  157.      represents a percentage of the gaze distance.
  158.  
  159.      [Ooutput-format]
  160.      The parameter output-format chooses between the  PIC  format
  161.      (0-default) or the PPM format (1).
  162.  
  163.      [Vverbose-mode]
  164.      The parameter verbose-mode supresses  any  messages  (0)  or
  165.      shows  listing  of  parameters (1), previous plus statistics
  166.      (2-default) or previous plus a line  by  line  echo  of  the
  167.      tracing (3-default on DOS and transputers).
  168.  
  169.      The scene data internal syntax (SFF) is described bellow.
  170.  
  171.      The image file will contain the ray traced image.  The image
  172.      file  has a 4 byte header composed of width LS and MS bytes,
  173.      height LS and MS bytes and RGB byte triplets starting in the
  174.      upper left corner line by line to the lower right corner.
  175.  
  176. RESTRICTIONS
  177.      The straightforward use:
  178.  
  179.        rtrace demo.sff demo.pic
  180.  
  181.      is not recommended, as ray tracing usually takes lots of CPU
  182.      time to execute.
  183.  
  184.      So, it is better to do:
  185.  
  186.        rtrace demo.sff demo.pic >demo.log &
  187.  
  188.      or then use nice (1) or similar strategies.
  189.  
  190. BUGS
  191.      No bugs known.  They have to be hidden  deep  somewhere,  as
  192.      usual.
  193.  
  194. DESCRIPTION
  195.      SFF (Simple File Format) description follows. This is a very
  196.      crude  ASCII  format,  almost like if generated by a lexical
  197.      analyser. The idea is to have other  programs  create  scene
  198.      descriptions  in  more sophisticated ways, and then feed the
  199.      tokenized results to this program. So,  it  behaves  accord-
  200.      ingly  to  the  UNIX  philosophy:  one program for one task.
  201.      Complaints are not wellcome!...
  202.  
  203.      There is a reasonable scene language  available  (SCN)  that
  204.      allows  the  creation  of scenes with much more flexibility;
  205.      the converter is called 'scn2sff' and  works  directly  with
  206.      this program.
  207.  
  208.      Note: the ^(circunflex) character represents start of line.
  209.  
  210.      [Start of File]
  211.      ^... Comment
  212.      ^Eye(X Y Z)
  213.      ^Look(X Y Z)
  214.      ^Up(X Y Z)
  215.      ^View_angle(H V) [1,89 degrees]
  216.      ^... Comment
  217.      ^Background(R G B)
  218.      ^Ambient(R G B)
  219.      ^... Comment
  220.      ^Light_type(Type) Position(X Y Z) Bright(R G B) ...
  221.        |                                                                    |
  222.        |                  /---------------------------/
  223.        |                  |
  224.        V                V
  225.       1-POINT:
  226.       2-DIRECTIONAL: Direction(X Y Z) Angle(La) Light_Factor(Lf)
  227.       3-EXTENDED:    Radius(R) Samples(N)
  228.      ^Etc
  229.      ^<NL>
  230.      ^... Comment
  231.      ^Surface_type(Type) Color(R G B) ...
  232.        |                                                 |
  233.        |        /----------------------/
  234.        |        |
  235.        V      V
  236.       1-: Dif(R G B) Spec(R G B) Phong(Pf) Metal(Mf) Trans(R G B)
  237.       2-: Smoothness(R G B) Metalness(R G B) Transmission(R G B)
  238.      ^Etc
  239.      ^<NL>
  240.      ^... Comment
  241.      ^Object_type(Type) Surface_ID(S) Refraction(Re) ...
  242.        |                                                                  |
  243.        |                     /------------------------/
  244.        |                     |
  245.        V                   V
  246.       1-SPHERE:          Center(X Y Z) Radius(R)
  247.       2-PARALLELIPIPED:  Center(X Y Z) Size(X Y Z)
  248.       3-PATCH:           Origin(X Y Z) Scale(X Y Z) Filename(...)
  249.       4-CONE/CYLINDER:   Base(X Y Z) Base_Radius(Rb) Apex(X Y Z)
  250.                          Apex_Radius(Ra)
  251.       5-POLYGON:         Origin(X Y Z) Scale(X Y Z) Filename(...)
  252.       6-TRIANGLE:        Origin(X Y Z) Scale(X Y Z) Filename(...)
  253.       7-TEXT:            Filename(...)
  254.      or
  255.       64-TEXTURE:        see below
  256.       65-TRANSFORMATION: Object_ID(I)
  257.                          Transform(X1 Y1 Z1 W1 ... X4 Y4 Z4 W4)
  258.       66-CSG 0:           Surface_ID(S)  Refraction(Re)  (Union-0
  259.      Sub-1 Int-2)
  260.          CSG 1:          Next CSG member
  261.          CSG 2:          End of CSG
  262.       67-LIST 0:         Surface_ID(S) Refraction(Re)
  263.          LIST 1:         End of List
  264.      ^Etc
  265.      ^<NL>
  266.      ^... Comment
  267.      ^Texture_type(Type) Object_ID(I)
  268.        |                 Transform(X1 Y1 Z1 W1 ... X4 Y4 Z4 W4)
  269.        |                 ...
  270.        |                  |
  271.        V                V
  272.       0-NULL:
  273.       1-CHECKER:   Surface_ID(S)
  274.       2-BLOTCH:    Scale(K) Surface_ID(S) [Filename(...) or -]
  275.       3-BUMP:      Scale(K)
  276.       4-MARBLE:    [Filename(...) or -]
  277.       5-FBM:       Offset(K) Scale(K) Omega(K) Lambda(L)
  278.                    Threshold(K) Octaves(O)
  279.                    [Filename(...) or -]
  280.       6-FBMBUMP:   Offset(K) Scale(K) Lambda(L) Octaves(O)
  281.       7-WOOD:      Color(R G B)
  282.       8-ROUND:     Scale(K)
  283.       9-BOZO:      Turbulence(K) [Filename(...) or -]
  284.       10-RIPPLES:  Frequency(K) Phase(K) Scale(K)
  285.       11-WAVES:    Frequency(K) Phase(K) Scale(K)
  286.       12-SPOTTED:  [Filename(...) or -]
  287.       13-DENTS:    Scale(K)
  288.       14-AGATE:    [Filename(...) or -]
  289.       15-WRINKLES: Scale(K)
  290.       16-GRANITE:  [Filename(...) or -]
  291.       17-GRADIENT: Turbulence(K) Direction(X Y Z)
  292.                    [Filename(...) or -]
  293.       18-IMAGEMAP: Turbulence(K) Mode(K) Axis(X Y) Filename(...)
  294.       19-GLOSS:    Scale(K)
  295.       20-BUMP3:    Scale(K) Size(K)
  296.      ^<NL>
  297.      ^... Comments
  298.      [End of File]
  299.  
  300.      1. Valid ranges of data
  301.  
  302.      RGB must be in [0,1[ (Note: RGB brightness of lights may  be
  303.      between  ]-300,300[;  negative  values mean to not attenuate
  304.      with distance).
  305.  
  306.      XYZ must be in [-10000,10000]
  307.  
  308.      Factor must be in [0,300[
  309.  
  310.      Filename must a valid filename for the operating system,  or
  311.      then '-', in which case data is read from the standard input
  312.      or the current SFF stream.
  313.  
  314.      2. Patch specification
  315.  
  316.      File format for PATCH (bicubic 4-sided patch):
  317.  
  318.      [Start]
  319.      ^Patch_1_Index(1 2 3 4 5 6 7 8 9 10 11 12)
  320.      ^Patch_2
  321.      ^Etc
  322.      ^<NL>
  323.      ^Patch_Index_1_Coords(X Y Z)
  324.      ^Patch_Index_2_Coords(X Y Z)
  325.      ^Etc
  326.      ^<NL>
  327.      ^...
  328.      [End]
  329.  
  330.      3. Polygon specification
  331.  
  332.      File format for POLYGON (n-sided planar polygon):
  333.  
  334.      [Start]
  335.      ^Polygon_1_Vertex_Number Polygon_1_Index(1 2 3 ...)
  336.      ^Polygon_2
  337.      ^Etc
  338.      ^<NL>
  339.      ^Polygon_Index_1_Coords(X Y Z)
  340.      ^Polygon_Index_2_Coords(X Y Z)
  341.      ^Etc
  342.      ^<NL>
  343.      ^...
  344.      [End]
  345.  
  346.      4. Triangle specification
  347.  
  348.      File format for TRIANGLE (3-sided polygon with  vertex  nor-
  349.      mals):
  350.  
  351.      [Start]
  352.      ^Triangle_1_Vertice_1(X Y Z) Normal_1(X Y Z)
  353.                  Vertice_2(X Y Z) Normal_2(X Y Z)
  354.                  Vertice_3(X Y Z) Normal_3(X Y Z)
  355.      ^Triangle_2
  356.      ^<NL>
  357.      ^...
  358.      [End]
  359.  
  360.      5. An example
  361.  
  362.      [Start of File]
  363.      View
  364.      25 25 7         - Eye point
  365.      0 0 0           - Look point
  366.      0 1 0           - Up vector
  367.      30 30           - View angles
  368.      Colors
  369.      0.196 0.6 0.8   - Background (Sky Blue)
  370.      0.1 0.1 0.1     - Ambient light
  371.      Lights
  372.      1 0 60 60 0.9 0.9 0.9  - Point Light 1
  373.      1 20 40 -7 0.9 0.9 0.9 - Point Light 2
  374.      <NL>
  375.      Surfaces
  376.      1 0.6 0.8 0.196 0.99 0.99 0.99 0 0 0 0 0 0 0 0
  377.      1 0.9 0.9 0.9 0.5 0.5 0.5 0.5 0.5 0.5 50 1 0 0 0
  378.      1 0.5 0.5 0.5 0.1 0.1 0.1 0.1 0.1 0.1 200 0.7 0.8 0.8 0.8
  379.      1 0.9 0.2 0.2 0.99 0.99 0.99 0 0 0 0 0 0 0 0
  380.      <NL>
  381.      Objects
  382.      5 1 1.0 0 0 0 15 15 15  - Polygon
  383.      4 1 2 3 4
  384.      <NL>
  385.      1 0 1
  386.      1 0 -1
  387.      -1 0 -1
  388.      -1 0 1
  389.      <NL>
  390.      2 2 1.0 0 2 0 7 2 3     - Parallelipiped
  391.      2 3 1.5 0 5 10 3 5 3    - Parallelipiped
  392.      1 4 1.0 7 15 -7 3       - Sphere
  393.      <NL>
  394.      Textures
  395.      2 1 2 0 0 0 0 2 0 0 0 0 2 0 0 0 0 1 0.4 4
  396.      4 2 5 0 0 0 0 5 0 0 0 0 5 0 0 0 0 1
  397.      5 4 10 0 0 0 1 10 0 0 1 1 10 0 0 0 0 1 0 0.6 0.5 2 0.1 6
  398.      <NL>
  399.      Demo / 11-OCT-1989 / Antonio Costa
  400.      [End of File]
  401.  
  402.      To ray trace without textures, do:
  403.  
  404.        rtrace demo.sff demo.pic >&demo.log
  405.  
  406.      else, do:
  407.  
  408.        rtrace t2 demo.sff demo.pic >&demo.log
  409.  
  410.      Another example with INESC symbol:
  411.  
  412.      [Start of File]
  413.      View
  414.      45.0 45.0 81.0  - Eye point
  415.      45.0 45.0 -81.0 - Look point
  416.       0.0  1.0  0.0  - Up vector
  417.      30 30           - View angles
  418.      Colors
  419.      0.196 0.6 0.8 - Background (Sky Blue)
  420.      0.3 0.3 0.3   - Ambient
  421.      Lights
  422.      1  0.0 100.0 100.0 1 1 1 - Light 1 (White)
  423.      1 90.0 100.0 100.0 1 1 0 - Light 2 (Yellow)
  424.      <NL>
  425.      Surfaces
  426.      1 0.557 0.420 0.137 0.8 0.7 0.7 0.2 0.3 0.3 30 0.8 0 0 0
  427.      1 0.137 0.420 0.557 0.5 0.5 0.6 0.5 0.5 0.4 5 0.2 0 0 0
  428.      1 0.600 0.800 0.200 0.9 0.9 0.9 0.0 0.0 0.0 1 0 0 0 0
  429.      <NL>
  430.      Objects
  431.      1 1 1.0 10.0 09.5 0.0 4.5 - Sphere
  432.      1 1 1.0 10.0 26.5 0.0 4.5
  433.      1 1 1.0 20.0 63.5 0.0 4.5
  434.      1 1 1.0 20.0 80.0 0.0 4.5
  435.      1 1 1.0 40.0 09.5 0.0 4.5
  436.      1 1 1.0 40.0 26.5 0.0 4.5
  437.      1 1 1.0 40.0 43.5 0.0 4.5
  438.      1 1 1.0 50.0 80.0 0.0 4.5
  439.      1 1 1.0 60.0 53.0 0.0 4.5
  440.      1 1 1.0 70.0 09.5 0.0 4.5
  441.      1 1 1.0 70.0 43.5 0.0 4.5
  442.      4 2 1.0 10.0 30.0 0.0 1.5 10.0 70.0 0.0 1.5 - Cylinder
  443.      1 2 1.0 10.0 70.0 0.0 1.5
  444.      4 2 1.0 10.0 70.0 0.0 1.5 17.5 77.5 0.0 1.5
  445.      4 2 1.0 12.5 12.0 0.0 1.5 20.0 19.5 0.0 1.5
  446.      1 2 1.0 20.0 19.5 0.0 1.5
  447.      4 2 1.0 20.0 19.5 0.0 1.5 20.0 60.0 0.0 1.5
  448.      4 2 1.0 22.5 61.0 0.0 1.5 37.5 46.0 0.0 1.5
  449.      4 2 1.0 37.5 12.0 0.0 1.5 30.0 19.5 0.0 1.5
  450.      1 2 1.0 30.0 19.5 0.0 1.5
  451.      4 2 1.0 30.0 19.5 0.0 1.5 30.0 33.5 0.0 1.5
  452.      1 2 1.0 30.0 33.5 0.0 1.5
  453.      4 2 1.0 30.0 33.5 0.0 1.5 37.5 41.0 0.0 1.5
  454.      4 2 1.0 30.0 26.5 0.0 1.5 36.5 26.5 0.0 1.5
  455.      4 2 1.0 40.0 47.0 0.0 1.5 40.0 70.0 0.0 1.5
  456.      1 2 1.0 40.0 70.0 0.0 1.5
  457.      4 2 1.0 40.0 70.0 0.0 1.5 47.5 77.5 0.0 1.5
  458.      4 2 1.0 42.5 12.0 0.0 1.5 50.0 19.5 0.0 1.5
  459.      1 2 1.0 50.0 19.5 0.0 1.5
  460.      4 2 1.0 50.0 19.5 0.0 1.5 50.0 43.0 0.0 1.5
  461.      1 2 1.0 50.0 43.0 0.0 1.5
  462.      4 2 1.0 50.0 43.0 0.0 1.5 57.5 50.5 0.0 1.5
  463.      4 2 1.0 67.5 12.0 0.0 1.5 60.0 19.5 0.0 1.5
  464.      1 2 1.0 60.0 19.5 0.0 1.5
  465.      4 2 1.0 60.0 19.5 0.0 1.5 60.0 33.5 0.0 1.5
  466.      1 2 1.0 60.0 33.5 0.0 1.5
  467.      4 2 1.0 60.0 33.5 0.0 1.5 67.5 41.0 0.0 1.5
  468.      5 3 1.0 0.0 4.0 0.0 200.0 200.0 200.0 - Polygon
  469.      4 1 2 3 4
  470.      <NL>
  471.       1.0 0.0  1.0
  472.       1.0 0.0 -1.0
  473.      -1.0 0.0 -1.0
  474.      -1.0 0.0  1.0
  475.      <NL>
  476.      <NL>
  477.      End
  478.      INESC Logo / 23-FEB-1989 / Antonio Costa
  479.  
  480. HISTORY
  481.      Copyright (C) 1988 1992 by Antonio Costa.
  482.      Permission is granted to use this file in whole or  in  part
  483.      for  any  purpose,  educational, recreational or commercial,
  484.      provided that this copyright notice is  retained  unchanged.
  485.      This  software  is  available  to  all  free  of  charge  by
  486.      anonymous FTP.
  487.  
  488.      11-Aug-92  Antonio Costa at INESC-Norte
  489.           Release 7.3.2
  490.           acc@asterix.inescn.pt acc@basinger.inescn.pt
  491.  
  492.  
  493.